<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en'>
<head>
  <meta content="text/html; charset=ISO-8859-1"  http-equiv="content-type" />
  <link rel="stylesheet" type="text/css" href="style.css" />
  <title>SOCI - reference</title>
</head>

<body>
<p class="banner">SOCI - The C++ Database Access Library</p>

<h2>Client interface reference</h2>

<div class="navigation">
<a href="#commontypes">commonly used types</a><br />
<a href="#session">class session</a><br />
<a href="#pool">class connection_pool</a><br />
<a href="#transaction">class transaction</a><br />
<a href="#into">function into</a><br />
<a href="#use">function use</a><br />
<a href="#statement">class statement</a><br />
<a href="#procedure">class procedure</a><br />
<a href="#typeconversion">class type_conversion</a><br />
<a href="#row">class row</a><br />
<a href="#columnproperties">class column_properties</a><br />
<a href="#values">class values</a><br />
<a href="#blob">class blob</a><br />
<a href="#rowid">class rowid</a><br />
<a href="#backendfactory">class backend_factory</a><br /><br />
<a href="#simpleclient">Simple client interface</a><br />
</div>

<p>The core client interface is a set of classes and free functions declared in
the <code>soci.h</code> header file. All names are dbeclared in the <code>soci</code>
namespace.</p>

<p>There are also additional names declared in the <code>soci::details</code>
namespace, but they are not supposed to be directly used by the users
of the library and are therefore not documented here. When such types
are used in the declarations that are part of the "public" interface,
they are replaced by "IT", which means "internal type". Types related
to the backend interface are named here, but documented on the <a
 href="backends.html">next page</a>.</p>

<h3 id="commontypes">commonly used types</h3>

<p>The following types are commonly used in the rest of the interface:</p>

<pre class="example">
// data types, as seen by the user
enum data_type { dt_string, dt_date, dt_double, dt_integer,
                 dt_unsigned_long, dt_long_long };

// the enum type for indicator variables
enum indicator { i_ok, i_null, i_truncated };

// the type used for reporting exceptions
class soci_error : public std::runtime_error { /* ... */ };
</pre>

<p>The <code>data_type</code> type defines the basic SOCI data types.
User provided data types need to be associated with one of these basic
types.</p>

<p>The <code>indicator</code> type defines the possible states of data.</p>

<p>The <code>soci_error</code> type is used for error reporting.</p>

<h3 id="session">class session</h3>

<p>The <code>session</code> class encapsulates the connection to the
database.</p>

<pre class="example">
class session
{
public:
    session();
    session(backend_factory const &amp; factory, std::string const &amp; connectString);
    session(std::string const &amp; backendName, std::string const &amp; connectString);
    explicit session(std::string const &amp; connectString);
    explicit session(connection_pool &amp; pool);

    ~session();

    void open(backend_factory const &amp; factory, std::string const &amp; connectString);
    void open(std::string const &amp; backendName, std::string const &amp; connectString);
    void open(std::string const &amp; connectString);
    void close();
    void reconnect();

    void begin();
    void commit();
    void rollback();

    <i>IT</i> once;
    <i>IT</i> prepare;

    template &lt;typename T&gt; <i>IT</i> operator&lt;&lt;(T const &amp; t);

    bool got_data() const;

    std::ostringstream &amp; get_query_stream();

    void set_log_stream(std::ostream * s);
    std::ostream * get_log_stream() const;

    std::string get_last_query() const;

    void uppercase_column_names(bool forceToUpper);

    details::session_backend * get_backend();

    std::string get_backend_name() const;
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Various constructors. The default one creates the session in the disconnected state.
  The others expect the backend factory object, or the backend name, or the URL-like
  composed connection string. The last constructor creates a session proxy associated
  with the session that is available in the given pool and releases it back to the pool
  when its lifetime ends. Example:
<pre class="example">
session sql(postgresql, "dbname=mydb");
session sql("postgresql", "dbname=mydb");
session sql("postgresql://dbname=mydb");
</pre>
  The constructors that take backend name as string load the shared library (if not yet loaded)
  with name computed as <code>libsoci_ABC.so</code> (or <code>libsoci_ABC.dll</code> on Windows)
  where <code>ABC</code> is the given backend name.
  </li>
  <li><code>open</code>, <code>close</code> and <code>reconnect</code> functions for
  reusing the same session object many times; the <code>reconnect</code> function attempts
  to establish the connection with the same parameters as most recently used with constructor
  or <code>open</code>. The arguments for <code>open</code> are treated in the same way as
  for constructors.
  </li>
  <li><code>begin</code>, <code>commit</code> and <code>rollback</code>
functions for transaction control.
  </li>
  <li><code>once</code> member, which is used for performing <i>instant</i>
queries that do not need to be separately prepared. Example:
<pre class="example">
sql.once &lt;&lt; "drop table persons";
</pre>
  </li>
  <li><code>prepare</code> member, which is used for statement
preparation - the result of the statement preparation must be provided
to the constructor of the <code>statement</code> class. Example:
<pre class="example">
int i;
statement st = (sql.prepare &lt;&lt;
                "insert into numbers(value) values(:val)", use(i));
</pre>
  </li>
  <li><code>operator&lt;&lt;</code> that is a shortcut forwarder to the
equivalent operator of the <code>once</code> member. Example:
<pre class="example">
sql &lt;&lt; "drop table persons";
</pre>
  </li>
  <li><code>got_data</code> returns true if the last executed query had non-empty result.</li>
  <li><code>get_query_stream</code> provides direct access to the stream object that is used
  to accumulate the query text and exists in particular to allow the user to imbue specific locale
  to this stream.</li>
  <li><code>set_log_stream</code> and <code>get_log_stream</code> functions for setting and getting
  the current stream object used for basic query logging. By default, it is <code>NULL</code>, which means no logging.
  The string value that is actually logged into the stream is one-line verbatim copy of the query string provided by the user,
  without including any data from the <code>use</code> elements. The query is logged exactly once, before the preparation step.</li>
  <li><code>get_last_query</code> retrieves the text of the last used query.</li>
  <li><code>uppercase_column_names</code> allows to force all column names to uppercase in dynamic row description;
  this function is particularly useful for portability, since various database servers
  report column names differently (some preserve case, some change it).</li>
  <li><code>get_backend</code> returns the internal
pointer to the concrete backend implementation of the session. This is
provided for advanced users that need access to the functionality that
is not otherwise available.</li>
  <li><code>get_backend_name</code> is a convenience forwarder to the same function
of the backend object.</li>
</ul>

<p>See <a href="basics.html">Connections and simple queries</a> for more
examples.</p>

<h3 id="pool">class connection_pool</h3>

<p>The <code>connection_pool</code> class encapsulates the thread-safe pool of connections
and ensures that only one thread at a time has access to any connection that it manages.</p>

<pre class="example">
class connection_pool
{
public:
    explicit connection_pool(std::size_t size);
    ~connection_pool();

    session &amp; at(std::size_t pos);

    std::size_t lease();
    bool try_lease(std::size_t &amp; pos, int timeout);
    void give_back(std::size_t pos);
};
</pre>

<p>The operations of the pool are:</p>

<ul>
  <li>Constructor that takes the intended size of the pool. After construction,
  the pool contains regular <code>session</code> objects in disconnected state.</li>
  <li><code>at</code> function that provides direct access to any given entry
  in the pool. This function is <i>non-synchronized</i>.</li>
  <li><code>lease</code> function waits until some entry is available (which means
  that it is not used) and returns the position of that entry in the pool, marking
  it as <i>locked</i>.</li>
  <li><code>try_lease</code> acts like <code>lease</code>, but allows to set up a
  time-out (relative, in milliseconds) on waiting. Negative time-out value means no time-out.
  Returns <code>true</code> if the entry was obtained, in which case its position
  is written to the <code>pos</code> parametr, and <code>false</code> if no entry
  was available before the time-out.</li>
  <li><code>give_back</code> should be called when the entry on the given position
  is no longer in use and can be passed to other requesting thread.</li>
</ul>
<p>Note: calls to <code>lease</code> and <code>give_back</code> are automated by the
dedicated constructor of the <code>session</code> class, see above.</p>

<h3 id="transaction">class transaction</h3>

<p>The class <code>transaction</code> can be used for associating the transaction
with some code scope. It is a RAII wrapper for regular transaction operations that
automatically rolls back in its destructor <i>if</i> the transaction was not explicitly
committed before.</p>
<pre class="example">
class transaction
{
public:
    explicit transaction(session & sql);

    ~transaction();

    void commit();
    void rollback();

private:
    // ...
};
</pre>

<p>Note that objects of this class are not notified of other transaction related operations
that might be executed by user code explicitly or hidden inside SQL queries.
It is not recommended to mix different ways of managing transactions.</p>

<h3 id="into">function into</h3>

<p>The function <code>into</code> is used for binding local output data
(in other words, it defines where the results of the query are stored).</p>

<pre class="example">
template &lt;typename T&gt;
<i>IT</i> into(T &amp; t);

template &lt;typename T, typename T1&gt;
<i>IT</i> into(T &amp; t, T1 p1);

template &lt;typename T&gt;
<i>IT</i> into(T &amp; t, indicator &amp; ind);

template &lt;typename T, typename T1&gt;
<i>IT</i> into(T &amp; t, indicator &amp; ind, T1 p1);

template &lt;typename T&gt;
<i>IT</i> into(T &amp; t, std::vector&lt;indicator&gt; &amp; ind);
</pre>

<p>Example:</p>

<pre class="example">
int count;
sql &lt;&lt; "select count(*) from person", into(count);
</pre>

<p>See <a href="exchange.html#bind_local">Binding local data</a>
for more examples.</p>

<h3 id="use">function use</h3>

<p>The function <code>use</code> is used for binding local input data (in
other words, it defines where the parameters of the query come from).</p>

<pre class="example">
template &lt;typename T&gt;
<i>IT</i> use(T &amp; t);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp; t, T1 p1);

template &lt;typename T&gt;
<i>IT</i> use(T &amp; t, indicator &amp; ind);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp; t, indicator &amp; ind, T1 p1);

template &lt;typename T&gt;
<i>IT</i> use(T &amp; t, std::vector&lt;indicator&gt; const &amp; ind);

template &lt;typename T, typename T1&gt;
<i>IT</i> use(T &amp; t, std::vector&lt;indicator&gt; const &amp; ind, T1 p1);
</pre>

<p>Example:</p>

<pre class="example">
int val = 7;
sql &lt;&lt; "insert into numbers(val) values(:val)", use(val);
</pre>

<p>See <a href="exchange.html#bind_local">Binding local data</a>
for more examples.</p>

<h3 id="statement">class statement</h3>

<p>The <code>statement</code> class encapsulates the prepared statement.</p>

<pre class="example">
class statement
{
public:
    statement(session &amp; s);
    statement(<i>IT</i> const &amp; prep);
    ~statement();

    statement(statement const &amp; other);
    void operator=(statement const &amp; other);

    void alloc();
    void bind(values &amp; v);
    void exchange(<i>IT</i> const &amp; i);
    void exchange(<i>IT</i> const &amp; u);
    void clean_up();

    void prepare(std::string const &amp; query);
    void define_and_bind();

    bool execute(bool withDataExchange = false);
    bool fetch();

    bool got_data() const;

    void describe();
    void set_row(row * r);
    void exchange_for_rowset(<i>IT</i> const &amp; i);

    details::statement_backend * get_backend();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor accepting the <code>session</code> object. This can
be used for later query preparation. Example:
<pre class="example">
statement stmt(sql);
</pre>
  </li>
  <li>Constructor accepting the result of using <code>prepare</code>
on the <code>session</code> object, see example provided above for the
    <code>session</code> class.</li>
  <li>Copy operations.</li>
  <li><code>alloc</code> function, which allocates necessary internal resources.</li>
  <li><code>bind</code> function, which is used to bind the <code>values</code>
object - this is used in the object-relational mapping and normally
called automatically.</li>
  <li>exchange functions for registering the binding of local data -
they expect the result of calling the <code>into</code> or <code>use</code>
functions and are normally invoked automatically.</li>
  <li><code>clean_up</code> function for cleaning up resources, normally
called automatically.</li>
  <li><code>prepare</code> function for preparing the statement for
repeated execution.</li>
  <li><code>define_and_bind</code> function for actually executing the
registered bindings, normally called automatically.</li>
  <li><code>execute</code> function for executing the statement. If its
parameter is <code>false</code> then there is no data exchange with
locally bound variables (this form should be used if later <code>fetch</code>
of multiple rows is foreseen). Returns <code>true</code> if there was at least
one row of data returned.</li>
  <li><code>fetch</code> function for retrieving the next portion of
the result. Returns <code>true</code> if there was new data.</li>
<li><code>got_data</code> return <code>true</code> if the most recent
execution returned any rows.</li>
  <li><code>describe</code> function for extracting the type
information for the result (note: no data is exchanged). This is normally
called automatically and only when dynamic resultset binding is used.</li>
  <li><code>set_row</code> function for associating the <code>statement</code>
and <code>row</code> objects, normally called automatically.</li>
  <li><code>exchange_for_rowset</code> as a special case for binding <code>rowset</code>
objects.</li>
  <li><code>get_backend</code> function that returns the internal
pointer to
the concrete backend implementation of the statement object. This is
provided
for advanced users that need access to the functionality that is not
otherwise available.</li>
</ul>

<p>See <a href="statements.html#preparation">Statement preparation and
repeated execution</a> for example uses.</p>

<p>Most of the functions from the <code>statement</code> class
interface are called automatically, but can be also used explicitly.
See <a href="interfaces">Interfaces</a> for the description of various way to use
this interface.</p>

<h3 id="procedure">class procedure</h3>

<p>The <code>procedure</code> class encapsulates the call to the stored
procedure and is aimed for higher portability of the client code.</p>

<pre class="example">
class procedure
{
public:
    procedure(<i>IT</i> const &amp; prep);

    bool execute(bool withDataExchange = false);
    bool fetch();
    bool got_data() const;
};
</pre>

<p>The constructor expects the result of using <code>prepare</code>
on the <code>session</code> object.</p>

<p>See <a href="statements.html#procedures">Stored procedures</a> for
examples.</p>

<h3 id="typeconversion">class type_conversion</h3>

<p>The <code>type_conversion</code> class is a traits class that is
supposed to be provided (specialized) by the user for defining
conversions to and from one of the basic SOCI types.</p>

<pre class="example">
template &lt;typename T&gt;
struct type_conversion
{
    typedef T base_type;

    static void from_base(base_type const &amp; in, indicator ind, T &amp; out);

    static void to_base(T const &amp; in, base_type &amp; out, indicator &amp; ind);
};
</pre>

<p>Users are supposed to properly implement the <code>from_base</code> and <code>to_base</code>
functions in their specializations of this template class.</p>

<p>See <a href="exchange.html#custom_types">Extending
SOCI to support custom (user-defined) C++ types</a>.</p>

<h3 id="row">class row</h3>

<p>The <code>row</code> class encapsulates the data and type information
retrieved for the single row when the dynamic rowset binding is used.</p>

<pre class="example">
class row
{
public:
    row();
    ~row();

    void uppercase_column_names(bool forceToUpper);

    std::size_t size() const;

    indicator get_indicator(std::size_t pos) const;
    indicator get_indicator(std::string const &amp; name) const;

    column_properties const &amp; get_properties (std::size_t pos) const;
    column_properties const &amp; get_properties (std::string const &amp; name) const;

    template &lt;typename T&gt;
    T get(std::size_t pos) const;

    template &lt;typename T&gt;
    T get(std::size_t pos, T const &amp; nullValue) const;

    template &lt;typename T&gt;
    T get(std::string const &amp; name) const;

    template &lt;typename T&gt;
    T get(std::string const &amp; name, T const &amp; nullValue) const;

    template &lt;typename T&gt;
    row const &amp; operator&gt;&gt;(T &amp; value) const;

    void skip(std::size_t num = 1) const;

    void reset_get_counter() const
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Default constructor that allows to declare a <code>row</code>
variable.</li>
  <li><code>uppercase_column_names</code> - see the same function in the <code>session</code> class.</li>
  <li><code>size</code> function that returns the number of columns in
the row.</li>
  <li><code>get_indicator</code> function that returns the indicator value
for the given column (column is specified by position - starting from 0
- or by name).</li>
  <li><code>get_properties</code> function that returns the properties
of the column given by position (starting from 0) or by name.</li>
  <li><code>get</code> functions that return the value of the column
given by position or name. If the column contains null, then these
functions either return the provided "default" <code>nullValue</code>
or throw an exception.</li>
  <li><code>operator&gt;&gt;</code> for convenience stream-like
extraction interface. Subsequent calls to this function are equivalent
to calling <code>get</code> with increasing position parameter,
starting from the beginning.</li>
  <li><code>skip</code> and <code>reset_get_counter</code> allow to change the
order of data extraction for the above operator.</li>
</ul>

<p>See <a href="exchange.html#dynamic">Dynamic resultset binding</a> for
examples.</p>

<h3 id="columnproperties">class column_properties</h3>

<p>The <code>column_properties</code> class provides the type and name
information about the particular column in a rowset.</p>

<pre class="example">
class column_properties
{
public:
    std::string get_name() const;
    data_type get_data_type() const;
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li><code>get_name</code> function that returns the name of the column.</li>
  <li><code>get_data_type</code> that returns the type of the column.</li>
</ul>

<p>See <a href="exchange.html#dynamic">Dynamic resultset binding</a> for
examples.</p>

<h3 id="values">class values</h3>

<p>The <code>values</code> class encapsulates the data and type
information and is used for object-relational mapping.</p>

<pre class="example">
class values
{
public:
    values();

    void uppercase_column_names(bool forceToUpper);

    indicator get_indicator(std::size_t pos) const;
    indicator get_indicator(std::string const &amp; name) const;

    template &lt;typename T&gt;
    T get(std::size_t pos) const;

    template &lt;typename T&gt;
    T get(std::size_t pos, T const &amp; nullValue) const;

    template &lt;typename T&gt;
    T get(std::string const &amp; name) const;
    
    template &lt;typename T&gt;
    T get(std::string const &amp; name, T const &amp; nullValue) const;

    template &lt;typename T&gt;
    values const &amp; operator&gt;&gt;(T &amp; value) const;

    void skip(std::size_t num = 1) const;
    void reset_get_counter() const;
    
    template &lt;typename T&gt;
    void set(std::string const &amp; name, T const &amp; value, indicator indic = i_ok);

    template &lt;typename T&gt;
    void set(const T &amp; value, indicator indic = i_ok);

    template &lt;typename T&gt;
    values &amp; operator&lt;&lt;(T const &amp; value);
};
</pre>

<p>This class contains the same members as the <code>row</code> class (with the same meaning)
plus:</p>
<ul>
  <li><code>set</code> function for storing values in named columns or in subsequent positions.</li>
  <li><code>operator&lt;&lt;</code> for convenience.</li>
</ul>

<p>See <a href="exchange.html#object_relational">Object-relational mapping</a>
for examples.</p>

<h3 id="blob">class blob</h3>

<p>The <code>blob</code> class encapsulates the "large object"
functionality.</p>

<pre class="example">
class blob
{
public:
    explicit blob(session &amp; s);
    ~blob();

    std::size_t getLen();
    std::size_t read(std::size_t offset, char * buf, std::size_t toRead);
    std::size_t write(std::size_t offset, char const * buf, std::size_t toWrite);
    std::size_t append(char const * buf, std::size_t toWrite);
    void trim(std::size_t newLen);

    details::blob_backend * get_backend();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor associating the <code>blob</code> object with the <code>session</code> object.</li>
  <li><code>get_len</code> function that returns the size of the BLOB
object.</li>
  <li><code>read</code> function that reads the BLOB data into provided
buffer.</li>
  <li><code>write</code> function that writes the BLOB data from
provided buffer.</li>
  <li><code>append</code> function that appends to the existing BLOB
data.</li>
  <li><code>trim</code> function that truncates the existing data to
the new length.</li>
  <li><code>get_backend</code> function that returns the internal
pointer to
the concrete backend implementation of the BLOB object. This is
provided
for advanced users that need access to the functionality that is not
otherwise available.</li>
</ul>

<p>See <a href="exchange.html#blob">Large objects (BLOBs)</a> for more
discussion.</p>

<h3 id="rowid">class rowid</h3>

<p>The <code>rowid</code> class encapsulates the "row identifier" object.</p>

<pre class="example">
class rowid
{
public:
    explicit rowid(Session &amp; s);
    ~rowid();

    details::rowid_backend * get_backend();
};
</pre>

<p>This class contains the following members:</p>
<ul>
  <li>Constructor associating the <code>rowid</code> object with the <code>session</code>
object.</li>
  <li><code>get_backend</code> function that returns the internal
pointer to
the concrete backend implementation of the <code>rowid</code> object.</li>
</ul>

<h3 id="backendfactory">class backend_factory</h3>

<p>The <code>backend_factory</code> class provides the abstract interface
for concrete backend factories.</p>

<pre class="example">
struct backend_factory
{
    virtual details::session_backend * make_session(
        std::string const &amp; connectString) const = 0;
};
</pre>

<p>The only member of this class is the <code>make_session</code> function
that is supposed to create concrete backend implementation of the
session object.</p>

<p>Objects of this type are declared by each backend and should be
provided to the constructor of the <code>session</code> class.
In simple programs users do not need to use this class directly, but
the example use is:</p>

<pre class="example">
backend_factory &amp; factory = postgresql;
std::string connectionParameters = "dbname=mydb";

session sql(factory, parameters);
</pre>

<h3 id="simpleclient">Simple client interface</h3>

<p>The simple client interface is provided with other languages in mind,
to allow easy integration of the SOCI library with script interpreters and those
languages that have the ability to link directly with object files using
the "C" calling convention.</p>
<p>The functionality of this interface is limited and in particular the
dynamic rowset description and type conversions are not supported in this release.
On the other hand, the important feature of this interface is that it does not
require passing pointers to data managed by the user, because all data is handled
at the SOCI side. This should make it easier to integrate SOCI with languages that
have constrained ability to understand the C type system.</p>
<p>Users of this interface need to explicitly <code>#include &lt;soci-simple.h&gt;</code>.</p>

<pre class="example">
typedef void * session_handle;
session_handle soci_create_session(char const * connectionString);
void soci_destroy_session(session_handle s);

void soci_begin(session_handle s);
void soci_commit(session_handle s);
void soci_rollback(session_handle s);

int soci_session_state(session_handle s);
char const * soci_session_error_message(session_handle s);
</pre>

<p>The functions above provide the <i>session</i> abstraction with the help of opaque handle.
The <code>soci_session_state</code> function returns <code>1</code> if there was no error
during the most recently executed function and <code>0</code> otherwise, in which
case the <code>soci_session_error_message</code> can be used to obtain a human-readable
error description.</p>
<p>Note that the only function that cannot report all errors this way is <code>soci_create_session</code>,
which returns <code>NULL</code> if it was not possible to create an internal object
representing the session. However, if the proxy object was created, but the connection
could not be established for whatever reason, the error message can be obtained in
the regular way.</p>

<pre class="example">
typedef void * statement_handle;
statement_handle soci_create_statement(session_handle s);
void soci_destroy_statement(statement_handle st);

int soci_statement_state(statement_handle s);
char const * soci_statement_error_message(statement_handle s);
</pre>

<p>The functions above create and destroy the statement object. If the statement cannot
be created by the <code>soci_create_statement</code> function, the error condition is set up in the related session object;
for all other functions the error condition is set in the statement object itself.</p>

<pre class="example">
int soci_into_string   (statement_handle st);
int soci_into_int      (statement_handle st);
int soci_into_long_long(statement_handle st);
int soci_into_double   (statement_handle st);
int soci_into_date     (statement_handle st);

int soci_into_string_v   (statement_handle st);
int soci_into_int_v      (statement_handle st);
int soci_into_long_long_v(statement_handle st);
int soci_into_double_v   (statement_handle st);
int soci_into_date_v     (statement_handle st);
</pre>

<p>These functions create new data items for storing query results (<i>into elements</i>).
These elements can be later identified by their position, which is counted from 0. For convenience,
these function return the position of the currently added element. In case of error,
<code>-1</code> is returned and the error condition is set in the statement object.</p>
<p>The <code>_v</code> versions create a <code>vector</code> into elements, which can be used
to retrieve whole arrays of results.</p>

<pre class="example">
int soci_get_into_state(statement_handle st, int position);
int soci_get_into_state_v(statement_handle st, int position, int index);
</pre>

<p>This function returns <code>1</code> if the into element at the given position has non-null value and <code>0</code> otherwise.
The <code>_v</code> version works with <code>vector</code> elements and expects an array index.</p>

<pre class="example">
int  soci_into_get_size_v(statement_handle st);
void soci_into_resize_v  (statement_handle st, int new_size);
</pre>

<p>The functions above allow to get and set the size of vector into element.</p>

<p>Note: the <code>soci_into_resize_v</code> always sets <i>all</i> into vectors in the given statement
to the same size, which guarantees that all vector into elements have equal size.</p>

<pre class="example">
char const * soci_get_into_string   (statement_handle st, int position);
int          soci_get_into_int      (statement_handle st, int position);
long long    soci_get_into_long_long(statement_handle st, int position);
double       soci_get_into_double   (statement_handle st, int position);
char const * soci_get_into_date     (statement_handle st, int position);

char const * soci_get_into_string_v   (statement_handle st, int position, int index);
int          soci_get_into_int_v      (statement_handle st, int position, int index);
long long    soci_get_into_long_long_v(statement_handle st, int position, int index);
double       soci_get_into_double_v   (statement_handle st, int position, int index);
char const * soci_get_into_date_v     (statement_handle st, int position, int index);
</pre>

<p>The functions above allow to retrieve the current value of the given into element.</p>

<p>Note: the <code>date</code> function returns the date value in the "<code>YYYY MM DD HH mm ss</code>" string format.</p>

<pre class="example">
void soci_use_string   (statement_handle st, char const * name);
void soci_use_int      (statement_handle st, char const * name);
void soci_use_long_long(statement_handle st, char const * name);
void soci_use_double   (statement_handle st, char const * name);
void soci_use_date     (statement_handle st, char const * name);

void soci_use_string_v   (statement_handle st, char const * name);
void soci_use_int_v      (statement_handle st, char const * name);
void soci_use_long_long_v(statement_handle st, char const * name);
void soci_use_double_v   (statement_handle st, char const * name);
void soci_use_date_v     (statement_handle st, char const * name);
</pre>

<p>The functions above allow to create new data elements that will be used to provide
data to the query (<i>use elements</i>). The new elements can be later identified by given name, which
must be unique for the given statement.</p>

<pre class="example">
void soci_set_use_state(statement_handle st, char const * name, int state);
</pre>

<p>The <code>soci_set_use_state</code> function allows to set the state of the given use element.
If the <code>state</code> parameter is set to non-zero the use element is considered non-null
(which is also the default state after creating the use element).</p>

<pre class="example">
int  soci_use_get_size_v(statement_handle st);
void soci_use_resize_v  (statement_handle st, int new_size);
</pre>

<p>These functions get and set the size of vector use elements (see comments for vector into elements above).</p>

<pre class="example">
void soci_set_use_string   (statement_handle st, char const * name, char const * val);
void soci_set_use_int      (statement_handle st, char const * name, int val);
void soci_set_use_long_long(statement_handle st, char const * name, long long val);
void soci_set_use_double   (statement_handle st, char const * name, double val);
void soci_set_use_date     (statement_handle st, char const * name, char const * val);

void soci_set_use_state_v    (statement_handle st, char const * name, int index, int state);
void soci_set_use_string_v   (statement_handle st, char const * name, int index, char const * val);
void soci_set_use_int_v      (statement_handle st, char const * name, int index, int val);
void soci_set_use_long_long_v(statement_handle st, char const * name, int index, long long val);
void soci_set_use_double_v   (statement_handle st, char const * name, int index, double val);
void soci_set_use_date_v     (statement_handle st, char const * name, int index, char const * val);
</pre>

<p>The functions above set the value of the given use element, for both single and vector elements.</p>

<p>Note: the expected format for the data values is "<code>YYYY MM DD HH mm ss</code>".</p>

<pre class="example">
int          soci_get_use_state    (statement_handle st, char const * name);
char const * soci_get_use_string   (statement_handle st, char const * name);
int          soci_get_use_int      (statement_handle st, char const * name);
long long    soci_get_use_long_long(statement_handle st, char const * name);
double       soci_get_use_double   (statement_handle st, char const * name);
char const * soci_get_use_date     (statement_handle st, char const * name);
</pre>

<p>These functions allow to inspect the state and value of named use elements.</p>
<p>Note: these functions are provide only for single use elements, not for vectors;
the rationale for this is that modifiable use elements are not supported for bulk operations.</p>

<pre class="example">
void soci_prepare(statement_handle st, char const * query);
int  soci_execute(statement_handle st, int withDataExchange);
int  soci_fetch(statement_handle st);
int  soci_got_data(statement_handle st);
</pre>

<p>The functions above provide the core execution functionality for the statement object
and their meaning is equivalent to the respective functions in the core C++ interface
described above.</p>

<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
  <tr>
    <td class="foot-link-left">
      <a href="beyond.html">Previous (Beyond SOCI)</a>
    </td>
    <td class="foot-link-right">
      <a href="backends.html">Next (Backends reference)</a>
    </td>
  </tr>
</table>

<p class="copyright">Copyright &copy; 2004-2006 Maciej Sobczak, Stephen Hutton</p>
</body>
</html>
